/*
 * Copyright 2012 Gayan Perera
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package gap.maven.script.components.api;

import java.util.List;

import org.apache.maven.model.Dependency;
import org.apache.maven.plugin.MojoExecutionException;

/**
 * This interface represents POM file in maven model. This expose a simple API
 * to reads its information.
 * 
 * @author gayan
 */
public interface POMArtifactFile extends BaseArtifact {

    /**
     * Returns an artifact file which represents the given classifier.
     * 
     * @param classifier
     *            classifier which is not null and empty.
     * @return an instance of {@link ArtifactFile}.
     */
    ArtifactFile getClassifier(String classifier);

    /**
     * Returns an artifact file which represents the given classifier and type.
     * 
     * @param type
     *            classifier which is not null and empty.
     * @param classifier
     *            classifier which is not null and empty.
     * 
     * @return an instance of {@link ArtifactFile}.
     */
    ArtifactFile getClassifier(String type, String classifier);

    /**
     * Returns true if there are dependencies defined in the POM. Calling this
     * before {@link #download()} will return <code>false</code>.
     * 
     * @return <code>true</code> if there are dependencies defined in the pom.
     */
    boolean hasDependencies();

    /**
     * Returns a list of {@link POMArtifactFile} for the dependencies defined in
     * this pom artifact.
     * 
     * @return {@link List} of dependency {@link POMArtifactFile}s.
     */
    List<POMArtifactFile> getDependencyPOMs();

    /**
     * Returns true if there are managed dependencies defined in the POM.
     * Calling this before {@link #download()} will return <code>false</code>.
     * 
     * @return <code>true</code> if there are managed dependencies defined in
     *         the pom.
     */
    boolean hasManagedDependencies();

    /**
     * Returns a list of {@link POMArtifactFile} for the managed dependencies
     * defined in this pom artifact.
     * 
     * @return {@link List} of dependency {@link POMArtifactFile}s.
     */
    List<POMArtifactFile> getManagedDependencyPOMs();

    /**
     * Returns the main artifact file of the POM. Calling this before caling
     * {@link #download()} will cause an {@link IllegalStateException} to be
     * thrown.
     * 
     * @return an instance of {@link ArtifactFile}.
     */
    ArtifactFile getMainArtifact();

    /**
     * Returns the main artifact file of the POM by passing in the type. This
     * used for main artifacts which are not jar files. Calling this before
     * calling {@link #download()} will cause an {@link IllegalStateException}
     * to be thrown.
     * 
     * @return an instance of {@link ArtifactFile}.
     */
    ArtifactFile getMainArtifact(String type);

    /**
     * Returns the packaging type of this POM.
     * 
     * @return packaging type of this pom artifact. ex: jar, war, etc
     */
    String getPackaging();

    /**
     * Find the version for the given artifact information in the POM's
     * dependency list. This will not search in managed dependency list.
     * 
     * @param groupId
     *            Group id to search for which cannot be null or empty.
     * @param artifactId
     *            Artifact id to search for which cannot be null or empty.
     * @param type
     *            Type to search for which will be ignore if the value is null
     *            or empty.
     * @param classifier
     *            Classifier to search for which will be ignore if the value is
     *            null or empty.
     * @return The version number of the artifact if found. Else null is
     *         returned.
     * @throws MojoExecutionException
     */
    String findVersionInDependencies(String groupId, String artifactId, String type, String classifier)
            throws MojoExecutionException;

    /**
     * Find the version for the given artifact information in the POM's depdency
     * list. This will not search in managed dependency list.
     * 
     * @param groupId
     *            Group id to search for which cannot be null or empty.
     * @param artifactId
     *            Artifact id to search for which cannot be null or empty.
     * @return The version number of the artifact if found. Else null is
     *         returned.
     * @throws MojoExecutionException
     */
    String findVersionInDependencies(String groupId, String artifactId) throws MojoExecutionException;

    /**
     * Find the version for the given artifact information in the POM's managed
     * depdency list. This will not search in dependency list.
     * 
     * @param groupId
     *            Group id to search for which cannot be null or empty.
     * @param artifactId
     *            Artifact id to search for which cannot be null or empty.
     * @param type
     *            Type to search for which will be ignore if the value is null
     *            or empty.
     * @param classifier
     *            Classifier to search for which will be ignore if the value is
     *            null or empty.
     * @return The version number of the artifact if found. Else null is
     *         returned.
     * @throws MojoExecutionException
     */
    String findVersionInManagedDependencies(String groupId, String artifactId, String type, String classifier)
            throws MojoExecutionException;

    /**
     * Find the version for the given artifact information in the POM's managed
     * depdency list. This will not search in dependency list.
     * 
     * @param groupId
     *            Group id to search for which cannot be null or empty.
     * @param artifactId
     *            Artifact id to search for which cannot be null or empty.
     * @return The version number of the artifact if found. Else null is
     *         returned.
     * @throws MojoExecutionException
     */
    String findVersionInManagedDependencies(String groupId, String artifactId) throws MojoExecutionException;

    
	/**
	 * Returns all the artifact files which are defined as dependencies of this pom. This includes
	 * transitive dependencies as well. The returned artifacts represents the type and the
	 * classifier which is defined in the dependency entry.
	 * 
	 * @return List of {@link ArtifactFile} which is not null.
	 */
	List<ArtifactFile> getDependecyArtifactFiles();
	
	
	/**
	 * Returns all the dependencies from the underlying maven project. This can be used to read the dependency 
	 * information without trying to resolve them instead of {@link #getDependencyPOMs()}.
	 * @return List of dependencies.
	 */
	List<Dependency> getDependencies();
	
    /**
     * Returns all the dependency management dependencies from the underlying maven project. 
     * This can be used to read the dependency information without trying to resolve them 
     * instead of {@link #getManagedDependencyPOMs()}.
     * @return List of dependencies.
     */
	List<Dependency> getManagedDependencies();
}
